<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Generators Reference &mdash; Geraldo Reports Documentation v0.4-alpha-5 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.4-alpha-5',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Geraldo Reports Documentation v0.4-alpha-5 documentation" href="index.html" />
    <link rel="next" title="Caching" href="caching.html" />
    <link rel="prev" title="Graphics Reference" href="graphics.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="caching.html" title="Caching"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="graphics.html" title="Graphics Reference"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Geraldo Reports Documentation v0.4-alpha-5 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="generators-reference">
<h1>Generators Reference<a class="headerlink" href="#generators-reference" title="Permalink to this headline">¶</a></h1>
<p>Generators are classes to generate a report instance to some data format. In
future we will have generators for XML, HTML, PS, images and so on.</p>
<div class="section" id="pdf-generator">
<h2>PDF Generator<a class="headerlink" href="#pdf-generator" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="geraldo.generators.PDFGenerator">
<em class="property">class </em><tt class="descclassname">geraldo.generators.</tt><tt class="descname">PDFGenerator</tt><a class="headerlink" href="#geraldo.generators.PDFGenerator" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Path: <strong>geraldo.generators.PDFGenerator</strong></p>
<p>This generator is the most mature generator we have. It generates PDF files to
be viewed on Adobe Acrobat Reader or similar software. It uses the awesome
library &#8216;ReportLab&#8217; to create them.</p>
<p><strong>Attributes:</strong></p>
<ul>
<li><p class="first"><strong>filename</strong> - Default: None</p>
<blockquote>
<p>You have to provide the filename you are creating, unless you provided the
attribute &#8216;canvas&#8217;</p>
</blockquote>
</li>
<li><p class="first"><strong>canvas</strong> - Default: None</p>
<blockquote>
<p><strong>New in version 0.3.5</strong></p>
<p>If you already have a canvas instantiated, you can provide it instead
of &#8216;filename&#8217; to generate this report inside. This is useful to generate
many reports in the same PDF.</p>
</blockquote>
</li>
<li><p class="first"><strong>return_canvas</strong> - Default: False</p>
<blockquote>
<p><strong>New in version 0.3.5</strong></p>
<p>If you set this to <strong>True</strong>, the file will not be saved and the generator
will return the canvas to you to use as you want.</p>
</blockquote>
</li>
<li><p class="first"><strong>multiple_canvas</strong> - Default: False</p>
<blockquote>
<p><strong>New in version 0.3.7</strong></p>
<p>This attribute has default value <strong>True</strong> if you have <strong>pyPDF</strong> library
installed on your PYTHONPATH.</p>
<p>It is useful to store canvas in a temporary directory and combine all in
once when finished the generating. This helps to gain on memory consuming.</p>
<p>You can find more about pyPDF on <a class="reference external" href="http://pypi.python.org/pypi/pyPdf/">http://pypi.python.org/pypi/pyPdf/</a></p>
</blockquote>
</li>
<li><p class="first"><strong>temp_directory</strong> - Default: &#8216;/tmp/&#8217;</p>
<blockquote>
<p>Regarding to temporary saving files on report processing, this attribute
can receive a string with directory path where save those files.</p>
</blockquote>
</li>
</ul>
<p>To use PDFGenerator you just do something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">PDFGenerator</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s">&#39;file.pdf&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>In <strong>filename</strong> argument you can use a file path string or a file output object.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">fp</span> <span class="o">=</span> <span class="nb">file</span><span class="p">(</span><span class="s">&#39;test.pdf&#39;</span><span class="p">,</span> <span class="s">&#39;w&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">PDFGenerator</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="n">fp</span><span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">resp</span> <span class="o">=</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">mimetype</span><span class="o">=</span><span class="s">&#39;application/pdf&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">PDFGenerator</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="n">resp</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="text-generator">
<h2>Text Generator<a class="headerlink" href="#text-generator" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="geraldo.generators.TextGenerator">
<em class="property">class </em><tt class="descclassname">geraldo.generators.</tt><tt class="descname">TextGenerator</tt><a class="headerlink" href="#geraldo.generators.TextGenerator" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Path: <strong>geraldo.generators.TextGenerator</strong></p>
<p>This generator is still in the development stage, but it already works well. It
can be used to generate text files or to print to matrix printers.</p>
<p>You can use it exactly like you would use PDF generator, but this has some more
features. When running <strong>&#8216;generate_by&#8217;</strong> report method, you can inform the
attribute &#8216;filename&#8217; like you do in PDF, but you could also do some other things.</p>
<p><strong>Attributes:</strong></p>
<ul>
<li><p class="first"><strong>row_height</strong> - Default: 0.5*cm</p>
<blockquote>
<p>Should be the equivalent height of a row plus the space between rows.
This is important to calculate how many rows a page has.</p>
</blockquote>
</li>
<li><p class="first"><strong>character_width</strong> - Default: 0.23*cm</p>
<blockquote>
<p>Should be the equivalent width of a character. This is important to
calculate how many columns a page has.</p>
</blockquote>
</li>
<li><p class="first"><strong>to_printer</strong> - Default: True</p>
<blockquote>
<p>Is a boolean variable which you can set to generate a text to matrix printer
or not. This controls whether escape characters will be in the output or not.</p>
</blockquote>
</li>
<li><p class="first"><strong>escape_set</strong> - Default: geraldo.generators.text.DEFAULT_ESCAPE_SET</p>
<blockquote>
<p>Is a dictionary with equivalence table to escape codes. As far as we know,
escape codes can vary depending on model or printer manufacturer
(i.e. Epson, Lexmark, HP, etc.). This attribute is useful to support this.
Default is ESC/P2 standard (Epson matrix printers)</p>
</blockquote>
</li>
<li><p class="first"><strong>filename</strong> - Default: None</p>
<blockquote>
<p>Is the file path you can optionally provide to save text to.</p>
</blockquote>
</li>
<li><p class="first"><strong>encode_to</strong> - Default: None</p>
<blockquote>
<p>Here you can provide the coding identifier to force Geraldo to encode the
output string in. Example: &#8216;latin-1&#8217;</p>
</blockquote>
</li>
<li><p class="first"><strong>manual_escape_codes</strong> - Default: False</p>
<blockquote>
<p>A boolean variable that sets whether escape codes are manually provided or not.</p>
</blockquote>
</li>
</ul>
<p><strong>Examples:</strong></p>
<p>Basic:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s">&#39;file.txt&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Returning the output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">output</span> <span class="o">=</span> <span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">)</span>
</pre></div>
</div>
<p>Setting row height and/or column width:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">output</span> <span class="o">=</span> <span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">,</span> <span class="n">row_height</span><span class="o">=</span><span class="mf">0.7</span><span class="o">*</span><span class="n">cm</span><span class="p">,</span> <span class="n">character_width</span><span class="o">=</span><span class="mf">0.2</span><span class="o">*</span><span class="n">cm</span><span class="p">)</span>
</pre></div>
</div>
<p>Forcing the generator to encode the output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">output</span> <span class="o">=</span> <span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">,</span> <span class="n">encode_to</span><span class="o">=</span><span class="s">&#39;latin-1&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Setting to be printed by a printer or not:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">output</span> <span class="o">=</span> <span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">,</span> <span class="n">to_printer</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
<p>Setting a set of escape codes for printer (matrix printers work with escape codes
set for special characters or to setup the output printing):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">geraldo.generators.text</span> <span class="kn">import</span> <span class="n">DEFAULT_ESCAPE_SET</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">my_escape_set</span> <span class="o">=</span> <span class="n">DEFAULT_ESCAPE_SET</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">my_escape_set</span><span class="p">[</span><span class="s">&#39;condensed&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">15</span><span class="p">)</span> <span class="o">+</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">17</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">output</span> <span class="o">=</span> <span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">,</span> <span class="n">to_printer</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">escape_set</span><span class="o">=</span><span class="n">my_escape_set</span><span class="p">)</span>
</pre></div>
</div>
<p>Forcing the output to print out escape codes before/after report or page print:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">MyTextGenerator</span><span class="p">(</span><span class="n">TextGenerator</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">to_printer</span> <span class="o">=</span> <span class="bp">True</span>
<span class="gp">... </span>    <span class="n">manual_escape_codes</span> <span class="o">=</span> <span class="bp">True</span>
<span class="gp">... </span>    <span class="n">escapes_report_start</span> <span class="o">=</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">15</span><span class="p">)</span> <span class="c"># Sets condensed mode</span>
<span class="gp">... </span>    <span class="n">escapes_report_end</span> <span class="o">=</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">18</span><span class="p">)</span> <span class="c"># Unsets condensed mode</span>
<span class="gp">... </span>    <span class="n">escapes_page_start</span> <span class="o">=</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">12</span><span class="p">)</span> <span class="o">+</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="c"># Form and line feed</span>
<span class="gp">... </span>    <span class="n">escapes_page_end</span> <span class="o">=</span> <span class="s">&#39;&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">output</span> <span class="o">=</span> <span class="n">my_report_instance</span><span class="o">.</span><span class="n">generate_by</span><span class="p">(</span><span class="n">MyTextGenerator</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="">Generators Reference</a><ul>
<li><a class="reference external" href="#pdf-generator">PDF Generator</a></li>
<li><a class="reference external" href="#text-generator">Text Generator</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="graphics.html"
                                  title="previous chapter">Graphics Reference</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="caching.html"
                                  title="next chapter">Caching</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/generators.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="caching.html" title="Caching"
             >next</a> |</li>
        <li class="right" >
          <a href="graphics.html" title="Graphics Reference"
             >previous</a> |</li>
        <li><a href="index.html">Geraldo Reports Documentation v0.4-alpha-5 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2009-2010, Marinho Brandao.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
    </div>
  </body>
</html>